<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>OpenID Connect without Kibana | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="oidc-guide.html" title="Configuring single sign-on to the Elastic Stack using OpenID Connect">
<link rel="prev" href="oidc-kibana.html" title="Configuring Kibana">
<link rel="next" href="authorization.html" title="User authorization">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="secure-cluster.html">Secure a cluster</a></span>
»
<span class="breadcrumb-link"><a href="oidc-guide.html">Configuring single sign-on to the Elastic Stack using OpenID Connect</a></span>
»
<span class="breadcrumb-node">OpenID Connect without Kibana</span>
</div>
<div class="navheader">
<span class="prev">
<a href="oidc-kibana.html">« Configuring Kibana</a>
</span>
<span class="next">
<a href="authorization.html">User authorization »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="oidc-without-kibana"></a>OpenID Connect without Kibana<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/oidc-guide.asciidoc">edit</a>
</h2>
</div></div></div>
<p>The OpenID Connect realm is designed to allow users to authenticate to Kibana and as
such, most of the parts of the guide above make the assumption that Kibana is used.
This section describes how a custom web application could use the relevant OpenID
Connect REST APIs in order to authenticate the users to Elasticsearch, with OpenID Connect.</p>
<p>Single sign-on realms such as OpenID Connect and SAML make use of the Token Service in
Elasticsearch and in principle exchange a SAML or OpenID Connect Authentication response for
an Elasticsearch access token and a refresh token. The access token is used as credentials for subsequent calls to Elasticsearch. The
refresh token enables the user to get new Elasticsearch access tokens after the current one
expires.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>The Elasticsearch Token Service can be seen as a minimal oAuth2 authorization server
and the access token and refresh token mentioned above are tokens that pertain
<em>only</em> to this authorization server. They are generated and consumed <em>only</em> by Elasticsearch
and are in no way related to the tokens ( access token and ID Token ) that the
OpenID Connect Provider issues.</p>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="_register_the_rp_with_an_openid_connect_provider"></a>Register the RP with an OpenID Connect Provider<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/oidc-guide.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The Relying Party ( Elasticsearch and the custom web app ) will need to be registered as
client with the OpenID Connect Provider. Note that when registering the
<code class="literal">Redirect URI</code>, it needs to be a URL in the custom web app.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="_openid_connect_realm"></a>OpenID Connect Realm<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/oidc-guide.asciidoc">edit</a>
</h3>
</div></div></div>
<p>An OpenID Connect realm needs to be created and configured accordingly
in Elasticsearch. See <a class="xref" href="oidc-guide-authentication.html" title="Configure Elasticsearch for OpenID Connect authentication">Configure Elasticsearch for OpenID Connect authentication</a></p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="_service_account_user_for_accessing_the_apis"></a>Service Account user for accessing the APIs<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/oidc-guide.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The realm is designed with the assumption that there needs to be a privileged entity
acting as an authentication proxy. In this case, the custom web application is the
authentication proxy handling the authentication of end users ( more correctly,
"delegating" the authentication to the OpenID Connect Provider ). The OpenID Connect
APIs require authentication and the necessary authorization level for the authenticated
user. For this reason, a Service Account user needs to be created and assigned a role
that gives them the <code class="literal">manage_oidc</code> cluster privilege. The use of the <code class="literal">manage_token</code>
cluster privilege will be necessary after the authentication takes place, so that the
the user can maintain access or be subsequently logged out.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /_security/role/facilitator-role
{
  "cluster" : ["manage_oidc", "manage_token"]
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1237.console"></div>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /_security/user/facilitator
{
  "password" : "&lt;somePasswordHere&gt;",
  "roles"    : [ "facilitator-role"]
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1238.console"></div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="_handling_the_authentication_flow"></a>Handling the authentication flow<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authentication/oidc-guide.asciidoc">edit</a>
</h3>
</div></div></div>
<p>On a high level, the custom web application would need to perform the following steps in order to
authenticate a user with OpenID Connect:</p>
<div class="olist orderedlist">
<ol class="orderedlist">
<li class="listitem">
<p>Make an HTTP POST request to <code class="literal">_security/oidc/prepare</code>, authenticating as the <code class="literal">facilitator</code> user, using the name of the
OpenID Connect realm in the Elasticsearch configuration in the request body. See the
<a class="xref" href="security-api-oidc-prepare-authentication.html" title="OpenID Connect Prepare Authentication API">OIDC prepare authentication API</a> for more details</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /_security/oidc/prepare
{
  "realm" : "oidc1"
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1239.console"></div>
</li>
<li class="listitem">
Handle the response to <code class="literal">/_security/oidc/prepare</code>. The response from Elasticsearch will contain 3 parameters:
<code class="literal">redirect</code>, <code class="literal">state</code>, <code class="literal">nonce</code>. The custom web application would need to store the values for <code class="literal">state</code>
and <code class="literal">nonce</code> in the user’s session (client side in a cookie or server side if session information is
 persisted this way) and redirect the user’s browser to the URL that will be contained in the
<code class="literal">redirect</code> value.
</li>
<li class="listitem">
<p>Handle a subsequent response from the OP. After the user is successfully authenticated with the
OpenID Connect Provider, they will be redirected back to the callback/redirect URI. Upon receiving
this HTTP GET request, the custom web app will need to make an HTTP POST request to
<code class="literal">_security/oidc/authenticate</code>, again - authenticating as the <code class="literal">facilitator</code> user - passing the URL
where the user’s browser was redirected to, as a parameter, along with the
values for <code class="literal">nonce</code> and <code class="literal">state</code> it had saved in the user’s session previously. If more than one
OpenID Connect realms are configured, the custom web app can specify the name of the realm to be
used for handling this, but this parameter is optional.
See <a class="xref" href="security-api-oidc-authenticate.html" title="OpenID Connect authenticate API">OIDC authenticate API</a> for more details</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /_security/oidc/authenticate
{
  "redirect_uri" : "https://oidc-kibana.elastic.co:5603/api/security/oidc/callback?code=jtI3Ntt8v3_XvcLzCFGq&amp;state=4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
  "state" : "4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
  "nonce" : "WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM",
  "realm" : "oidc1"
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1240.console"></div>
<p>Elasticsearch will validate this and if all is correct will respond with an access token that can be used
as a <code class="literal">Bearer</code> token for subsequent requests and a refresh token that can be later used to refresh the given
access token as described in <a class="xref" href="security-api-get-token.html" title="Get token API">get token API</a>.</p>
</li>
<li class="listitem">
<p>At some point, if necessary, the custom web application can log the user out by using the
<a class="xref" href="security-api-oidc-logout.html" title="OpenID Connect logout API">OIDC logout API</a> passing the access token and refresh token as parameters. For example:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /_security/oidc/logout
{
  "token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  "refresh_token": "vLBPvmAB6KvwvJZr27cS"
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1241.console"></div>
<p>If the realm is configured accordingly, this may result in a response with a <code class="literal">redirect</code> parameter indicating where
the user needs to be redirected in the OP in order to complete the logout process.</p>
</li>
</ol>
</div>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="oidc-kibana.html">« Configuring Kibana</a>
</span>
<span class="next">
<a href="authorization.html">User authorization »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
